Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Resolve build warnings #2380

Merged
merged 2 commits into from
Dec 30, 2023
Merged

Conversation

stefan6419846
Copy link
Collaborator

This fixes #1941 by cleaning up wrong references and adding new docs. Some notes about this:

  • Building the docs now works without prior package installation.
  • The intersphinx mapping will now always use the objects of the Python version used for the docs build.
  • The intersphinx mapping for Pillow has been added.
  • Links to private methods in the developer docs have been replaced by inline code as they are not part of the Sphinx docs.
  • Some broken/outdated/strange docstrings have been fixed.
  • New classes have been added to the docs. Module-specific classes have been added to the modules where they are being used directly, some generic classes/modules have been put into new files/pages.
  • We have to exclude some members to avoid duplicate definitions.

Current output:

(venv) stefan@localhost:~/temp/pypdf> rm -rf build/ && LANG=C sphinx-build -n -T -b html docs build/sphinx/html
Running Sphinx v7.2.6
making output directory... done
loading intersphinx inventory from https://docs.python.org/3.9/objects.inv...
loading intersphinx inventory from https://pillow.readthedocs.io/en/latest/objects.inv...
[autosummary] generating autosummary for: dev/cmaps.md, dev/deprecations.md, dev/documentation.md, dev/intro.md, dev/pdf-format.md, dev/pypdf-parsing.md, dev/pypdf-writing.md, dev/releasing.md, dev/testing.md, index.rst, ..., user/metadata.md, user/migration-1-to-2.md, user/pdf-version-support.md, user/pdfa-compliance.md, user/post-processing-in-text-extraction.md, user/reading-pdf-annotations.md, user/robustness.md, user/streaming-data.md, user/suppress-warnings.md, user/viewer-preferences.md
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=True, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 57 source files that are out of date
updating environment: [new config] 57 added, 0 changed, 0 removed
reading sources... [100%] user/viewer-preferences
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] user/viewer-preferences
/home/stefan/temp/pypdf/pypdf/xmp.py:docstring of pypdf.xmp.XmpInformation.rdfRoot:1: WARNING: py:class reference target not found: xml.dom.minidom.Element
generating indices... genindex py-modindex done
highlighting module code... [100%] pypdf.xmp
writing additional pages... search done
copying images... [100%] user/nup-dest2.png
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in build/sphinx/html.

The remaining issue is about

pypdf/pypdf/xmp.py

Lines 228 to 231 in a91e9f6

@property
def rdfRoot(self) -> XmlElement: # deprecated
deprecate_with_replacement("rdfRoot", "rdf_root", "4.0.0")
return self.rdf_root
scheduled for removal in version 4.0.0 where I could not find a clean/nice solution for now.

Copy link

codecov bot commented Dec 29, 2023

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (a91e9f6) 94.35% compared to head (c3d559c) 94.35%.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2380   +/-   ##
=======================================
  Coverage   94.35%   94.35%           
=======================================
  Files          43       43           
  Lines        7584     7584           
  Branches     1519     1519           
=======================================
  Hits         7156     7156           
  Misses        265      265           
  Partials      163      163           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Copy link
Member

@MartinThoma MartinThoma left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice work!

I'm not quite sure yet if we want to document all of those publicly (e.g. the protocols), but we can make them private again if people get confused.

@MartinThoma MartinThoma merged commit 2cdc0d5 into py-pdf:main Dec 30, 2023
14 checks passed
@stefan6419846
Copy link
Collaborator Author

We need them to due to type hints, thus there is not much to do here unfortunately.

@stefan6419846 stefan6419846 deleted the docs-warnings branch December 30, 2023 15:16
MartinThoma added a commit that referenced this pull request Jan 19, 2024
## What's new

pypdf==4.0.0 is a big milestone forward:

* We finally have a layout-mode text extraction.
  This enables users who want to detect / extract tables
  with heuristics to give it a try.
* We deprecated a lot of the old PyPDF2 API that was either
  not following PEP8 naming styles or was not using a
  property. Users comming from PyPDF2 might want to switch
  first to pypdf<4.0.0 to get helpful error messages
  that show the new API in their speicific cases.

A big 'Thank you!' the the whole pypdf community for your
work. Thanks to you, pypdf is better than ever.

Kudos to @shartzog who added the layout-mode with his first
contribution!

### Deprecations (DEP)
-  Drop Python 3.6 support (#2369) by @MartinThoma
-  Remove deprecated code (#2367) by @MartinThoma
-  Remove deprecated XMP properties (#2386) by @stefan6419846

### New Features (ENH)
-  Add "layout" mode for text extraction (#2388) by @shartzog
-  Add Jupyter Notebook integration for PdfReader (#2375) by @MartinThoma
-  Improve/rewrite PDF permission retrieval (#2400) by @stefan6419846

### Bug Fixes (BUG)
-  PdfWriter.add_uri was setting the wrong type (#2406) by @pmiller66
-  Add support for GBK2K cmaps (#2385) by @stefan6419846

### Documentation (DOC)
-  Add pmiller66 for #2406 as a contributor by @MartinThoma
-  Add missing expand parameter (#2393) by @Atomnp
-  Resolve build warnings (#2380) by @stefan6419846
-  Fix testing prerequisites (#2381) by @stefan6419846
-  Improve formatting of contributors page (#2383) by @stefan6419846
-  Add Tobeabellwether as a contributor for #2341 by @MartinThoma

### Developer Experience (DEV)
-  Make dependabot aware of our PR prefixes (#2415) by @stefan6419846
-  Fail on Sphinx issues (#2405) by @stefan6419846
-  Move title check to own workflow (#2384) by @MasterOdin
-  Write to temporary files instead of the working directory (#2379) by @stefan6419846
-  Ensure that the PR titles have the correct format (#2378) by @stefan6419846

### Maintenance (MAINT)
-  Complete FileSpecificationDictionaryEntries constants (#2416) by @MartinThoma
-  Return None instead of -1 when page is not attached (#2376) by @MartinThoma
-  Replace warning with logging.error (#2377) by @MartinThoma

### Testing (TST)
-  Add missing pytest.mark.samples annotations (#2412) by @kitterma
-  Correctly close temporary files (#2396) by @stefan6419846
-  Fix  side effect #2379 (#2395) by @pubpub-zz
-  Add test for layout extraction mode (#2390) by @MartinThoma

### Code Style (STY)
-  Use the UserAccessPermissions enum (#2398) by @MartinThoma
-  Run black (#2370) by @MartinThoma

[Full Changelog](3.17.4...4.0.0)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3.12.0: sphinx warnings reference target not found
2 participants